Inside Macintosh: Sound

Managing an Asynchronous Play From Disk

The Sound Manager allows you to play a sound file asynchronously with the SndStartFilePlay function by defining a completion routine that sets a global flag to alert the application to dispose of the sound channel when the sound is done playing. Completion routines are thus similar to callback procedures, but they are easier to use in that you do not need to install them. The Sound Manager automatically executes them when a play from disk ends, whether it has ended because the application called the SndStopFilePlay function, because the application disposed of the sound channel in which the sound was playing, or because the sound has finished playing.

You define a completion routine like this:



 
PROCEDURE MySoundCompletionRoutine (chan: SndChannelPtr);

Note that unlike callback procedures, completion routines have only one parameter, a pointer to a sound channel. Thus, for the completion routine to set the application's A5 world properly, you should pass the value of the application's A5 in the userInfo field of the sound channel, like this:



 
gSndChan^.userInfo := SetCurrentA5;

Then your completion routine can look in the userInfo field of the sound channel to set A5 correctly before it can access any application global variables. Listing 1-33 defines a completion routine that sets A5 correctly.

Listing 33 Defining a completion routine



 
PROCEDURE MySoundCompletionRoutine (chan: SndChannelPtr);

VAR

    myA5:       LongInt;

BEGIN

    myA5 := SetA5(chan^.userInfo);                  {set my A5}

    gCompletionPerformed := TRUE;                   {set a global flag}

    myA5 := SetA5(myA5);                            {restore the original A5}

END;

The completion routine defined in Listing 1-33 sets a global flag variable to indicate that the completion routine has been called. To start a sound file playing, you can use a routine analogous to that defined in Listing 1-32 , but when allocating a sound channel, you need only allocate a queue of a single sound command. You can than use a procedure analogous to that defined in Listing 1-30 to check the flag once each time through the application's event loop and dispose of the sound channel if the flag is set.

If you do use the SndStartFilePlay function to play sounds asynchronously, then you can pause, restart, and stop play simply by using the SndPauseFilePlay and SndStopFilePlay functions.

You use SndPauseFilePlay to temporarily suspend a sound from playing. If a sound is playing and you call SndPauseFilePlay , then the sound is paused. If the sound is paused and you call SndPauseFilePlay again, then the sound resumes playing. Hence, the SndPauseFilePlay routine acts like a pause button on a tape player, which toggles the tape between playing and pausing. (You can determine the current state of a play from disk by using the SndChannelStatus function. See "Obtaining Information About a Single Sound Channel" for more details.) Finally, you can use SndStopFilePlay to stop the file from playing.